home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / Amiga_Mail_Vol2 / Archives / Plain / ma91 / version / Version.txt
Encoding:
Text File  |  1991-04-15  |  7.8 KB  |  262 lines
  1. (c)  Copyright 1991 Commodore-Amiga, Inc.   All rights reserved.
  2. The information contained herein is subject to change without notice,
  3. and is provided "as is" without warranty of any kind, either expressed
  4. or implied.  The entire risk as to the use of this information is
  5. assumed by the user.
  6.  
  7.  
  8.  
  9.  
  10.  
  11. 2.0 Version Strings
  12.  
  13.  
  14. By Carolyn Scheppner
  15.  
  16.  
  17.  
  18.  
  19. Unlike the 1.3 version command, the 2.0 version command has the ability 
  20. to search Amiga files for a version string.  If you try the 2.0 version 
  21. command on any of the 2.0 Workbench commands, you will find that almost 
  22. all Workbench commands now contain these special version strings.  For 
  23. example, running version on the current version of  SYS:Utilities/More 
  24. will output More 37.2.
  25.  
  26. This embedded version string provides a simple way for a user to 
  27. determine the specific version of a command.  This is extremely useful 
  28. for bug reports and phone support.  You may enter these strings in your 
  29. code yourself and update them by hand when required, or you may 
  30. automate updates by using the bumprev tool (provided on a variety of 
  31. DevCon disk sets and also in the Preliminary Software Toolkit II).  
  32.  
  33.  
  34.  
  35. Hand-Coded Version Strings
  36.  
  37. The hand-coded method can be used in text files and is often quite 
  38. suitable for simple programs with a single code module.  If you code 
  39. the version strings by hand, they should be formatted like the examples 
  40. below.  The example hand-coded strings are for a program named myapp, 
  41. version 37.1, date 20-Mar-91 (20.3.91):
  42.  
  43.  
  44. In C:
  45.  
  46. UBYTE versiontag[] = "\0$VER: appname 37.1 (20.3.91)";
  47.  
  48.  
  49.  
  50. In assembler:
  51.  
  52. versiontag      
  53.         
  54. dc.b    
  55. 0,'$VER: myapp 37.1 (20.3.91)',0
  56.  
  57.  
  58.  
  59. In a text file:
  60.  
  61. $VER: myapp.doc 37.1 (20.3.91)
  62.  
  63.  
  64.  
  65. Note that the NULL ("\0" or 0,) at the beginning of the versiontag 
  66. string is not necessary but can be useful if you choose to #define the 
  67. string and wish to give a version number to  a C program with no data 
  68. segment.  With the initial NULL, you can concatenate a #defined 
  69. versiontag string onto an arbitrary immediate string used in your code 
  70. to get the versiontag into your code segment.
  71.  
  72.  
  73.  
  74. Automating Version Numbering with Bumprev
  75.  
  76. The bumprev tool and the include files it creates are what we use 
  77. internally to give version numbers to system ROM modules, disk-based 
  78. devices and libraries, and 2.0 Workbench and Extras commands.  Bumprev 
  79. creates or updates three files -- a name_rev.rev file which contains 
  80. the current revision number, and the C and assembler include files 
  81. called name_rev.h and name_rev.i.  These include files contain #defines 
  82. (.h) or macros (.i) to define the name, version, revision, and date of 
  83. your program in a variety of string and numeric formats.
  84.  
  85. By using the appropriate include file in one or more of your code 
  86. modules, you can use these #defines (or macros) in place of hardcoded 
  87. version and revision information.  This way, whenever you ``bumprev'' 
  88. your revision files and recompile (or reassemble) your program, all 
  89. version, revision, and date references in your program will be 
  90. automatically updated.  You can even include a bumprev call in your 
  91. makefile for automatic revision bumping on every make (although this 
  92. can update the version number more often than is really necessary).
  93.  
  94.  
  95. The usage of bumprev is:        
  96.         
  97. bumprev <version> <name_rev>
  98.  
  99. For example:                            
  100. bumprev 37 myapp_rev
  101.  
  102.  
  103. The first time you use the above example bumprev call, it creates a 
  104. myapp_rev.rev file containing ``1'', and myapp_rev.h and .i files 
  105. containing a variety of version and revision #defines (or macros) for 
  106. version 37.1.  The next time you use the same bumprev command it 
  107. updates the files so that all #defines (or macros) are for version 
  108. 37.2.
  109.  
  110. Bumprev does have some caveats.  If you accidently type ``bumprev 37 
  111. myapp'' (instead of myapp_rev), bumprev will gladly overwrite any 
  112. myapp.h or myapp.i file you happen to have rather than complain or 
  113. automatically insert _rev into the output file names.  Also, to make a 
  114. major version switch (for example from 36 to 37), you must first delete 
  115. the myapp_rev.rev file to make bumprev start the revisions over again 
  116. at 1.  Note that the 2.0 convention is for a major version number of 37 
  117. (to match the OS major version).
  118.  
  119. Here are example _rev.h and _rev.i files as generated by bumprev, and 
  120. fragments of C and assembler code which include and reference these 
  121. files.
  122.  
  123.  
  124. Example myapp_rev.h generated by bumprev:
  125.  
  126.  
  127. #define      VERSION       37
  128. #define      REVISION      1
  129. #define      DATE          "20.3.91"
  130. #define      VERS          "myapp 37.1"
  131. #define      VSTRING       "myapp 37.1 (20.3.91)\n\r"
  132. #define      VERSTAG       "\0$VER: myapp 37.1 (20.3.91)"
  133.  
  134.  
  135. Code example which includes myapp_rev.h:
  136.  
  137. /* myapp.c */
  138.  
  139. #include <exec/types.h>
  140. #include <dos/dos.h>
  141.  
  142. /* stdlib.h and stdio.h contain prototypes for exit and printf.
  143.  * Amiga.lib IO users could instead use <clib/alib_protos.h>
  144.  *  and  <clib/alib_stdio_protos.h>
  145.  */
  146. #include <stdlib.h>
  147. #include <stdio.h>
  148. #include "myapp_rev.h"
  149.  
  150.  
  151. /* NOTE: we reference VERSTAG version string for C:VERSION to find */
  152. UBYTE versiontag[] = VERSTAG;
  153.  
  154. /* NOTE: we concatenate program name and version (VERS) with our 
  155. copyright */
  156. UBYTE Copyright[] = VERS " Copyright (c) 1991 CATS, Inc.  All Rights Reserved";
  157.  
  158.  
  159. void main(int argc,char **argv)
  160.     {
  161.     /* Print our Copyright string.
  162.      * Copyright string includes our myapp _rev.h version and date
  163.      */ 
  164.     printf("%s\n",Copyright);
  165.     exit(RETURN_OK);
  166.     }
  167.  
  168.  
  169.  
  170. Example mylib_rev.i generated by bumprev:
  171.  
  172.  
  173. VERSION     EQU  37
  174. REVISION    EQU   1
  175. DATE       MACRO
  176.     dc.b    '20.3.91'
  177.     ENDM
  178. VERS       MACRO
  179.     dc.b    'mylib 37.1'
  180.     ENDM
  181. VSTRING    MACRO
  182.     dc.b    'mylib 37.1 (20.3.91)',13,10,0
  183.     ENDM
  184. VERSTAG    MACRO
  185.     dc.b    0,'$VER: mylib 37.1 (20.3.91)',0
  186.     ENDM
  187.  
  188.  
  189.  
  190.  
  191. Code example which includes mylib_rev.i:
  192.  
  193. * This is an example of an initial library code module
  194. * Mylib_rev.i is generated with bumprev
  195.  
  196.       nolist
  197.         include "exec/types.i"
  198.         include "exec/initializers.i"
  199.         include "exec/libraries.i"
  200.         include "exec/resident.i"
  201.  
  202.         include "mylib.i"
  203.         include "mylib_rev.i"       ; Bumprev revision include file
  204.       list
  205.  
  206.             ; external
  207.         xref    InitLib             ; init function
  208.         xref    FuncTable           ; function table
  209.         xref    EndSkip             ; End of code segment
  210.  
  211.  
  212. ; code at start of file in case anyone tries to execute the library as a program
  213.  
  214.         entry   FalseStart
  215. FalseStart
  216.         moveq   #-1,d0
  217.         rts
  218.  
  219.  
  220. ResidentNode
  221.         dc.w    RTC_MATCHWORD       ; RT_MATCHWORD
  222.         dc.l    ResidentNode        ; RT_MATCHTAG
  223.         dc.l    EndSkip             ; RT_ENDSKIP
  224.         dc.b    RTF_AUTOINIT        ; RT_FLAGS
  225.         dc.b    VERSION             ; RT_VERSION        ;From mylib_rev.i
  226.         dc.b    NT_LIBRARY          ; RT_TYPE
  227.         dc.b    0                   ; RT_PRI
  228.         dc.l    LibName             ; RT_NAME
  229.         dc.l    IDString            ; RT_IDString       ;Contains VSTRING
  230.         dc.l    InitTable           ; RT_SIZE           ;  from mylib_rev.i
  231.  
  232.  
  233.  
  234. LibName:        DC.B    'mylib.library',0
  235. IDString:       VSTRING                                 ;From mylib_rev.i
  236.         CNOP    0,2
  237.  
  238. InitTable
  239.         dc.l    XMyLibBase_Size
  240.         dc.l    FuncTable
  241.         dc.l    DataTable
  242.         dc.l    InitLib
  243.  
  244. DataTable
  245.             ; standard library stuff
  246.         INITBYTE    LN_TYPE,NT_LIBRARY
  247.         INITLONG    LN_NAME,LibName
  248.         INITBYTE    LIB_FLAGS,LIBF_SUMUSED!LIBF_CHANGED
  249.         INITWORD    LIB_VERSION,VERSION                 ;From mylib_rev.i
  250.         INITWORD    LIB_REVISION,REVISION               ;From mylib_rev.i
  251.         INITLONG    LIB_IDSTRING,IDString               ;Contains VSTRING
  252.                                                         ;  from mylib_rev.i
  253.             ; library specific stuff
  254.  
  255.             ; end of init list
  256.         dc.l        0
  257.  
  258.         end
  259.  
  260.  
  261.  
  262.